III NPC Chopper / HELI_CLASSIC for GTA San Andreas
==================================================

Author: Johnzi

Thank you for downloading and using this mod.

This mod adds the classic Police Chopper from the GTA III / Vice City / LCS
style into GTA San Andreas, using a custom internal system called
HELI_CLASSIC.

Important:
this chopper does NOT use the native GTA San Andreas helicopter as its main
vehicle. It is NOT the regular SA Police Maverick / Polmav, and it does NOT
use San Andreas' native CHeli physics for movement, combat or destruction.

The goal of this mod is to recreate the classic police chopper inside GTA SA
as a separate subsystem, inspired by GTA III behavior.


REQUIREMENTS
============

1. GTA San Andreas PC 1.0

   This mod was made for the classic PC version of GTA San Andreas, preferably
   using the 1.0 US executable.

   Do not use:
   - GTA San Andreas Definitive Edition
   - the newer Steam version without downgrade
   - 1.01 / 2.0 executables without compatibility support

2. ASI Loader

   The file IIIHelibase.SA.asi will not load by itself in a clean GTA install.
   You need an ASI Loader installed in your GTA SA folder.

   Common examples:
   - Ultimate ASI Loader
   - Silent ASI Loader
   - dinput8.dll ASI Loader

   If the mod does not work and heli_classic_runtime.log does not appear in
   the main GTA folder, the ASI was probably not loaded. In that case, check
   your ASI Loader installation.

3. Backup recommended

   Make a backup of your GTA SA folder or, at minimum, these files:

   data\vehicles.ide
   data\handling.cfg

   This package includes prepared data files. If you use other mods, you may
   need to merge the lines manually instead of replacing the entire files.


HOW TO INSTALL
==============

Open the folder:

Put the files on your GTA SA folder

Copy ALL contents from inside that folder into your main GTA SA directory.

Correct example:

GTA San Andreas\
    heli_classic.ini
    audio\
        heli_classic\
            Bullet1.wav
            Bullet2.wav
            Bullet3.wav
            Chatter1.wav
            ...
            rotor1.wav
            rotor2.wav
            rotor3.wav
    data\
        vehicles.ide
        handling.cfg
    scripts\
        IIIHelibase.SA.asi
        chopper.dff
        CHOPPER.TXD
        spotlight.txd

Do not place the folder "Put the files on your GTA SA folder" inside your GTA
directory. You must copy its CONTENTS into the main game folder.


DO NOT EDIT / DO NOT RENAME
===========================

To avoid bugs, do not rename, move or edit these files:

scripts\IIIHelibase.SA.asi
scripts\chopper.dff
scripts\CHOPPER.TXD
scripts\spotlight.txd
heli_classic.ini
audio\heli_classic\*.wav

Also do not change this section in heli_classic.ini:

[612]
name=chopper
type=heli_classic
archetype=gta3_police_chopper
suppress_native_heli_pipeline=true

Model ID 612 is used as the classic chopper slot.
Changing this ID or trying to turn it into a native GTA SA helicopter may
break the mod.


WHAT THIS MOD DOES
==================

When CJ reaches a high enough wanted level, the mod creates the classic Police
Chopper using the HELI_CLASSIC system.

Main features:

- Classic GTA III-style police chopper.
- Does not use the native Polmav as the main chopper.
- Does not use GTA SA native helicopter physics.
- Spawns during police pursuits.
- Two choppers can appear at 6 stars.
- Movement, attacks and crash behavior inspired by GTA III.
- Functional spotlight.
- Front white light.
- Rear blinking red light.
- Custom rotor sounds.
- Custom bullet sounds.
- Police radio / chatter.
- Rotor dust near the ground.
- Damage from guns and RPGs.
- Reward and crime behavior when the chopper is shot down.
- HUD, minimap and police-presence integration.

Compatibility note:
the mod may use a small invisible native identity layer only for detection,
allowing GTA SA and other mods to recognize HELI_CLASSIC as a police
helicopter. This layer is not the main chopper, does not render, does not
collide, has no AI of its own, does not use native weapons and does not replace
the classic HELI_CLASSIC behavior.


HOW TO TEST
===========

1. Start GTA SA.
2. Enter the game in an outdoor area.
3. Get 3 or more wanted stars.
4. Wait for the chopper to appear.
5. At 6 stars, two choppers may appear.

The chopper should not appear while CJ is inside interiors.
If CJ is diving, the chopper should remain above the water surface.


LOG FILE
========

The mod creates this file in the main GTA SA folder:

heli_classic_runtime.log

The log helps diagnose problems.

It is reset every time GTA SA starts and has a size limit. This prevents huge
logs during long sessions.

If you need help, send this file together with an explanation of the problem.


QUICK TROUBLESHOOTING
=====================

Problem:
the mod does absolutely nothing.

Check:
- Does heli_classic_runtime.log exist in the main GTA folder?

If it does NOT exist:
- The ASI Loader is not installed or is not loading the ASI.
- Check dinput8.dll, vorbisFile.dll or any other ASI Loader you use.

If it exists:
- Open the log and check the first lines.

Correct:

HELI_CLASSIC CONFIG: loaded: heli_classic.ini
HELI_CLASSIC CONFIG: section [612] parsed
HELI_CLASSIC REGISTRY: model 612 registered as ClassicVehicleType::HeliClassic

Problem:
CONFIG not found.

Solution:
- Place heli_classic.ini in the main GTA SA folder.
- Optionally, it may also be placed in scripts\heli_classic.ini.

Problem:
chopper.dff not found / chopper.txd not found.

Solution:
- Make sure these files are in scripts:

scripts\chopper.dff
scripts\CHOPPER.TXD

Problem:
spotlight.txd not found or the spotlight does not appear.

Solution:
- Check:

scripts\spotlight.txd

Problem:
sounds do not play.

Solution:
- Check:

audio\heli_classic\rotor1.wav
audio\heli_classic\Bullet1.wav
audio\heli_classic\Chatter1.wav

Problem:
the native Police Maverick / Polmav appears instead of the classic chopper.

Solution:
- Make sure heli_classic.ini is loading.
- Make sure suppress_native_heli_pipeline=true.
- Make sure the correct ASI is located at scripts\IIIHelibase.SA.asi.


ABOUT MODLOADER
===============

This package was prepared for direct installation into the GTA SA folder.

Some files may work through ModLoader, but the safest installation method for
this package is copying the contents directly into the main GTA SA directory.

If you want to use ModLoader:
- keep the ASI in scripts, or make sure your ASI Loader loads ASIs from the mod;
- keep heli_classic.ini in the main GTA SA folder or in scripts;
- keep the audio files in audio\heli_classic.

To avoid problems, direct installation is recommended.


COMPATIBILITY
=============

Recommended:
- GTA San Andreas PC 1.0
- ASI Loader installed
- clean or lightly modded game

May conflict with:
- mods that replace the entire vehicles.ide file;
- mods that use or change model ID 612;
- mods that heavily modify the police / wanted level system;
- mods that aggressively replace CHeli / Polmav behavior;
- other ASIs that hook weapons, projectiles, helicopters, coronas or radar.


CREDITS / THANKS
================

Author:
- Johnzi

Special thanks:
- RE3 team and contributors
- GTA San Andreas Reversed community and contributors
- Plugin-SDK
- Visual Studio
- Magic.TXD
- Blender

This mod exists to preserve and port the classic Police Chopper to GTA San
Andreas. It was made with a focus on GTA III-style behavior, while using its
own architecture to work properly inside San Andreas.

Have fun.